home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 5
/
Apprentice-Release5.iso
/
Source Code
/
Libraries
/
Bitmap Libraries 2.0
/
Lisp Interface
/
BitMapLisp.txt
< prev
next >
Wrap
Text File
|
1996-03-10
|
45KB
|
1,412 lines
file BitMapLisp.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved.
ABOUT BITMAP...
Copyright (C) 1996 by John Montbriand. All Rights Reserved.
Distribute freely in areas where the laws of copyright apply.
Use at your own risk.
Do not distribute modified copies.
These various BitMap libraries are for free!
This file describes the Macintosh Common Lisp interface
to the bitmap routines.
ABOUT THE AUTHOR...
Comments, questions, or suggestions are always welcome.
John Montbriand tinyjohn@sasknet.sk.ca
P.O. Box. 1133
Saskatoon Saskatchewan Canada
S7K 3N2
WHY IS IT FOR FREE?
none of your business,
but if you have some business for me, I'll see what I can do..
OUTLINE OF TOPICS
INSTALLATION INSTRUCTIONS
BITMAPS, WHAT ARE THEY?
IMPLEMENTATION NOTES
MATERIALS
LEGAL STUFF
FURTHER REFERENCE
SERVICES PROVIDED (OVERVIEW)
BE CAREFUL (CAVEATS)
OTHER COOL THINGS YOU CAN DO
OVERVIEW OF ROUTINES
SPECIFIC ROUTINE DESCRIPTIONS
INSTALLATION INSTRUCTIONS
To install the bitmaps package in your system, move the files
BitMaps.lisp and BitMapsLib.o (found in the folder entitled
'Library Folder Stuff') into the 'Library' folder inside of the
MCL directory.
Once this has been done, the bitmaps package can be conveniently
loaded and imported into the current package using the following
commands:
(require :bitmaps)
(use-package :bitmaps)
see the file BitMapExamples.lisp for an example of how to load
the bitmaps package once it has been correctly installed in the
Library folder.
BITMAPS, WHAT ARE THEY?
Well, they're like little black and white computer screens in memory
that you can do drawing in before transfering the images you
draw on them to the screen. Drawing things off screen and then
placing them on screen creates the feel of instantaneous, flicker
free drawing.
BitMaps are a data structure used to store black and white images
off-screen. You can use quickdraw to draw directly into bitmaps
and create images for placement on the screen, or you can take
images from the screen, place them in a bitmap, do various
transformations to them, and then put them back on the screen.
QuickDraw GrafPorts draw into BitMap structures, and, as a matter
of fact, all screen drawing on early macintoshes was implemented
through BitMaps that were memory mapped to the screen hardware.
The big advantage: BitMaps provide a way to do simple high quality
graphics while at the same time requiring very little memory.
IMPLEMENTATION NOTES
This implementation stores each bitmap in a single, contiguous,
non-relocatable memory block refered to using a pointer. The first
14 bytes of the memory block contain the Bitmap data structure,
while the remaining bytes are used to store the raster data.
MATERIALS
The BitMap format itself is the copyright property of Apple
computer and has been known to the public since 1983.
The routines documented herein are the copyright property of
John Montbriand. I am making these routines available to the
macintosh programming community because I feel it's about time
someone did! They're fun, easy to use, and practical. I hope
all who find them will use them well.
Compiled and tested with MPW C, MWC, SC, MrC, MPW PPC, MCL2, MCL3.
LEGAL STUFF
These libraries are provided for free and you may use them
in any program you make; however, if you're particular about
having signed documentation that proves this fact in your posession
then, as I would like to ensure these libraries are widely used,
I would be glad provide such documents for you.
I don't think this is entirly necessary, but I can understand
that some folks feel quite strongly about such issues and prefer
to do things in writing.
If you would like for me to send you a signed document saying
that you have license to use these routines in your programs,
then send me a couple of bucks to cover postage and handling
and I'll send you back a signed letter saying you have license
to use these routines in any software you make.
I think two or three dollars is fair as I don't really get a big
thrill out of printing stuff out and mailing it, and that's usually
enough to cover postage to anywhere in the world. I s'pose you'd have
to figure out how much it would cost for me to mail a letter to you
from here in Canada.
FURTHER REFERENCE
BitMap.h and BitMap.c contain routines for accessing and manipulating
BitMap data stored in pointers. For more information about BitMaps,
offscreen drawing, pointers, C, etc.. refer to the following sources:
"Bitmaps" (2-9) in the "Basic QuickDraw" chapter of Inside Macintosh:
Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley.
A discussion of the Bitmap data structure and how it applies to
GrafPorts.
"Boolean Transfer Modes With 1-Bit Pixels" (3-8) in the "QuickDraw Drawing"
chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer,
Inc. Addison-Wesley.
BitMaps are 1-Bit Pixel data structures. This part discusses the
various transfer modes you can use while drawing into BitMaps.
"Copying Bits Between Graphics Ports" (3-32) in the "QuickDraw Drawing"
chapter of Inside Macintosh: Imaging With QuickDraw by Apple
Computer, Inc. Addison-Wesley.
A discussion of the Bitmap data structure and how it applies to
GrafPorts.
"Copying Images" (3-112) in the "QuickDraw Drawing" chapter of
Inside Macintosh: Imaging With QuickDraw by Apple
Computer, Inc. Addison-Wesley.
A discussion of the CopyBits routine and the various parameter
combinations you can use with it. This is followed by
a discussion of the CopyMask routine.
Technical note #163 "Adding Color With CopyBits" by Chris Derossi
A discussion of how to draw in colour using bitmaps.
Technical note #193 "So Many Bitmaps, So Little Time" by Rick Blair
A look at the BitMapToRegion routine.
Technical note #41 "Drawing Into an Offscreen Bitmap" by
Jim Friedlander & Ginger Jernigan
A talk about offscreen bitmaps, and how to use them.
Inside Macintosh: Memory by Apple Computer, Inc. Addison-Wesley.
A discussion of memory managment, pointers, what they are, and
how to use them.
The C Programming Language 2nd edition by Brian W. Kernighan
and Dennis M. Ritchie. Prentice Hall.
Macintosh Common Lisp Reference
Common Lisp 2nd edition by Guy L. Steele Jr. Digital Press.
Comments for the routines provided herein have been included in the
file BitMap.h.
Also, there is a 411 help file.
SERVICES PROVIDED (OVERVIEW)
- routines for creating bitmap structures in memory.
- rotate functions for rotating bitmaps 90 degrees left and right,
- flip functions for flipping bitmap data both vertically
and horizontally,
- a trace edges routine for tracing the edges of an image,
- a rotation routine for rotating a bitmap to a particular angle,
- a routine for duplicating bitmaps,
- a routine for comparing bitmaps,
- routines providing the painbucket tool and lasso tool effects,
- transfer routines for transfering bitmap data to and from the
PICT format,
- a complete set of logical operations on bitmaps,
- a complete set of pixel oriented routines for testing, setting,
clearing, and toggling individual pixels in bitmaps,
- routines and a macro allowing you to quickly and easily draw
into bitmaps,
- routines for copying bitmap images to the current grafport,
BE CAREFUL (CAVEATS)
I think these routines are safe to use, but you should do your own
testing. I have provided the source code, and if you find any bugs,
please let me know right away so I can provide corrections in
future versions.
I advertise a finder's fee of $10.00 cash for errors in any
of my products.
OTHER COOL THINGS YOU CAN DO
bitmaps provide a convenient, storage efficient way to
implement zero - one adjacency matrices that are incredibly
useful for working with directed graphs.
OVERVIEW OF ROUTINES
creating your own bitmaps:
(new-bitmap width height) -> a bitmap
(kill-bitmap bitmap &rest other-bitmaps)
rotating a bitmap image 90 degrees to the left or to the right:
(rotate-bitmap-right bitmap) -> a bitmap
(rotate-bitmap-left bitmap) -> a bitmap
flipping a bitmap image horizontally or vertically:
(flip-bitmap-vertically bitmap) -> a bitmap
(flip-bitmap-horizontally bitmap) -> a bitmap
rotating a bitmap image to a particular angle:
(rotate-bitmap bitmap h-center v-center angle) -> a bitmap
duplicating a bitmap:
(duplicate-bitmap bitmap) -> a bitmap
the paint bucket function:
(paint-bucket-bitmap bitmap h v) -> a bitmap
the lasso function:
(lasso-bitmap bitmap) -> a bitmap
the trace edges function:
(trace-bitmap-edges bitmap) -> a bitmap
transfer functions for converting to and from the PICT format:
(picture-to-bitmap bitmap) -> a bitmap
(bitmap-to-picture bitmap) -> a picture
logical operations on bitmaps:
(and-bitmaps bitmap-a bitmap-b) -> a bitmap
(or-bitmaps bitmap-a bitmap-b) -> a bitmap
(xor-bitmaps bitmap-a bitmap-b) -> a bitmap
(complement-bitmap bitmap) -> a bitmap
comparison:
(equal-bitmaps bitmap-a bitmap-b) -> T or NIL
pixel oriented functions:
(test-bitmap-pixel bitmap x y) -> T or NIL
(set-bitmap-pixel bitmap hpos vpos)
(clear-bitmap-pixel bitmap hpos vpos)
(toggle-bitmap-pixel bitmap x y) -> T or NIL
routines for drawing into bitmaps:
(with-focused-bitmap bitmap {form}*) -> bitmap
routines for copying bitmap data:
(plot-bitmap bitmap hpos vpos mode)
a routine for converting pascal strings into bitmaps:
(string-to-bitmap the-string &optional the-font-spec) -> a bitmap
SPECIFIC ROUTINE DESCRIPTIONS
new-bitmap
formal declaration:
(new-bitmap width height) -> a bitmap
arguments:
width the width of the requested bitmap
height the height of the requested bitmap
return value:
a pointer to a Bitmap data structure.
if an error occurs, NULL is returned.
description:
new-bitmap creates a new bitmap pointer with the requested
dimensions. The raster data is initialized to zeros, and if
there is not enough memory to allocate the bitmap, NewBitMap
will return NULL.
example application:
The following creates a new bitmap pointer 100 pixels wide
and 200 pixels tall.
(let (mybits)
(setf mybits (new-bitmap 100 200))
...
)
notes:
You can call #_DisposePtr to dispose of a bitmap pointer created by
new-bitmap The routine kill-bitmap calls #_DisposePtr.
kill-bitmap
formal declaration:
(kill-bitmap bitmap &rest other-bitmaps)
arguments:
one or more bitmaps
return value:
none.
description:
kill-bitmap disposes of bitmaps allocated by:
new-bitmap, duplicate-bitmap, rotate-bitmap-right, rotate-bitmap-left,
flip-bitmap-vertically, flip-bitmap-horizontally, rotate-bitmap,
paint-bucket-bitmap, lasso-bitmap, trace-bitmap-edges,
picture-to-bitmap, and-bitmaps, or-bitmaps, xor-bitmaps,
complement-bitmap, or string-to-bitmap.
It's your general all purpose bitmap disposal function.
example application:
The following creates a new bitmap pointer 100 pixels wide
and 200 pixels tall and then disposes of it by calling kill-bitmap
(let (mybits)
(setf mybits (new-bitmap 100 200))
...
(kill-bitmap mybits))
notes:
kill-bitmap simply calls #_DisposePtr.
rotate-bitmap-right
formal declaration:
(rotate-bitmap-right bitmap) -> a bitmap
arguments:
bits a bitmap
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the right.
if an error occurs, rotate-bitmap-right will return the value NULL.
description:
rotate-bitmap-right creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the right. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the right
before copying the image to the current grafport.
(prog (the-bits rotated-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf rotated-bits (rotate-bitmap-right the-bits))
(plot-bitmap rotated_bits 0 0 #$srcCopy)
(kill-bitmap the-bits rotated-bits))
notes:
rotate-bitmap-right takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling rotate-bitmap and specifying
a 90 degree angle.
rotate-bitmap-left
formal declaration:
(rotate-bitmap-left bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the left.
if an error occurs, rotate-bitmap-left will return the value NULL.
description:
rotate-bitmap-left creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the left. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the left
before copying the image to the current grafport.
(prog (the-bits rotated-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf rotated-bits (rotate-bitmap-left the-bits))
(plot-bitmap rotated_bits 0 0 #$srcCopy)
(kill-bitmap the-bits rotated-bits))
notes:
rotate-bitmap-left takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling rotate-bitmap and specifying
a -90 degree angle.
flip-bitmap-vertically
formal declaration:
(flip-bitmap-vertically bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped upside down.
if an error occurs, flip-bitmap-vertically will return the value NULL
description:
flip-bitmap-vertically creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped upside
down. The resulting bitmap will be the same size as
the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped upside down before
copying the new flipped image to the current grafport.
(prog (the-bits flippin-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf flippin-bits (flip-bitmap-vertically the-bits))
(plot-bitmap flippin-bits 0 0 #$srcCopy)
(kill-bitmap the-bits flippin-bits))
notes:
none.
flip-bitmap-horizontally
formal declaration:
(flip-bitmap-horizontally bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped horizontally.
if an error occurs, flip-bitmap-horizontally will return the value NULL.
description:
flip-bitmap-horizontally creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped horizontally.
The resulting bitmap will be the same size as the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped horizontally before
copying the new flipped image to the current grafport.
(prog (the-bits flippin-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf flippin-bits (flip-bitmap-horizontally the-bits))
(plot-bitmap flippin-bits 0 0 #$srcCopy)
(kill-bitmap the-bits flippin-bits))
notes:
none.
rotate-bitmap
formal declaration:
(rotate-bitmap bitmap h-center v-center angle) -> a bitmap
arguments:
bits a bitmap pointer
cx the horizontal center of rotation
cy the vertical center of rotation
angle the angle (in degrees) to rotate the image. both positive
and negative values are ok. This is an integer number.
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated around the center
cx and cy angle degrees.
if an error occurs, rotate-bitmap will return the value NULL.
description:
rotate-bitmap creates a new bitmap containing the image from
the parameter bitmap pointer rotated angle degrees about the
center (cx, cy). The resultant bitmap will have the same dimensions
as the parameter bitmap regardless of the angle specified.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 35 degrees to the right
before copying the rotated image to the current grafport.
(prog (the-bits round-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf round-bits (rotate-bitmap the-bits 50 50 35))
(plot-bitmap round-bits 0 0 #$srcCopy)
(kill-bitmap the-bits round-bits))
notes:
rotate-bitmap has a speedy implementation built on top of the
fixed math routines. For more information about fixed math
refer to the Mathematical and Logical Utilities chapter of
Inside Macintosh: Operating System Utilities.
duplicate-bitmap
formal declaration:
(duplicate-bitmap bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an
exact duplicate of the bitmap parameter.
if an error occurs, duplicate-bitmap will return the value NULL.
description:
duplicate-bitmap creates a copy of the bitmap parameter.
example application:
In this example, we make a new bitmap, duplicate it, put it
on the screen, and then dispose of the resulting bitmaps.
(prog (the-bits extra-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf extra-bits (duplicate-bitmap the-bits 50 50 35))
(plot-bitmap extra-bits 0 0 #$srcCopy)
(kill-bitmap the-bits extra-bits))
notes:
none.
paint-bucket-bitmap
formal declaration:
(paint-bucket-bitmap bitmap h v) -> a bitmap
arguments:
bits a bitmap pointer
h the horizontal position to start painting
v the vertical position to start painting
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak out starting from the point
(h, v).
if an error occurs, paint-bucket-bitmap will return the value NULL.
description:
paint-bucket-bitmap works like the paint bucket tool found in
most graphical applications. It calls the routine SeedFill
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the paint-bucket-bitmap routine starting at the point (50,50).
(prog (the-bits painted-bits)
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
(setf painted-bits (paint-bucket-bitmap the-bits 50 50))
(plot-bitmap painted-bits 0 0 #$srcCopy)
(kill-bitmap the-bits painted-bits))
notes:
paint-bucket-bitmap calls SeedFill. For further information about
SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
lasso-bitmap
formal declaration:
(lasso-bitmap bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak in from the edges of the
bitmap.
if an error occurs, lasso-bitmap will return the value NULL.
description:
lasso-bitmap works like the lasso bucket tool found in
most graphical applications. It calls the routine CalcMask
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the lasso-bitmap routine.
(prog (the-bits lasso-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
;; create a mask for the image
(setf lasso-bits (lasso-bitmap the-bits 50 50))
;; plot the mask on the screen
(plot-bitmap lasso-bits 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap the-bits lasso-bits))
notes:
lasso-bitmap calls CalcMask. For further information about
CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
trace-bitmap-edges
formal declaration:
(trace-bitmap-edges bitmap) -> a bitmap
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing containing the original
image with the edges traced.
if an error occurs, trace-bitmap-edges will return the value NULL.
description:
trace-bitmap-edges performs the 'trace edges' command found in
many graphical applications returning a new bitmap
containing the traced image..
example application:
In this example, we make a new bitmap and create a new bitmap
containing the traced image.
(prog (the-bits traced-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
;; create a mask for the image
(setf traced-bits (trace-bitmap-edges the-bits))
;; plot the new image on the screen
(plot-bitmap traced-bits 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap the-bits traced-bits))
notes:
none.
equal-bitmaps
formal declaration:
(equal-bitmaps bitmap-a bitmap-b) -> T or NIL
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
T or NIL
description:
returns T if the two bitmaps are the same size and
contain the same image content. returns NIL if either
bitmap is NULL.
example application:
In this example, we make a new bitmap and create a two bitmaps
and compare them by calling equal-bitmaps
(prog (bitmap-one bitmap-two)
;; make some bitmaps
(setf bitmap-one (new-bitmap 100 200))
(setf bitmap-two (new-bitmap 100 200))
;; normally, we'd draw some images on the bitmaps here
(if (equal-bitmaps bitmap-one bitmap-two)
(princ "the bitmaps, they are the same!")
(princ "the bitmaps, they are not the same!"))
(terpri)
;; recover the storage
(kill-bitmap bitmap-one bitmap-two))
notes:
equal-bitmaps takes into account that either bitmap may have
different rowBytes values, and the possibility that garbage
values may be stored in the unused bits off to the right
of the boundary rectangle.
picture-to-bitmap
formal declaration:
(picture-to-bitmap bitmap) -> a bitmap
arguments:
pic a handle to a QuickDraw picture
return value:
a newly created bitmap pointer containing a black and white
representation of the image drawn by the quickdraw picture
parameter.
if an error occurs, picture-to-bitmap will return the value NULL.
description:
picture-to-bitmap creates a new bitmap pointer the using the size
information provided in the QuickDraw picture pointer parameter
and draws the picture in the bitmap before returning the bitmap.
example application:
In this example, we call GetPicture to retrieve a picture from
a resource file and then we convert it to a bitmap by calling
the routine picture-to-bitmap
(prog (the-bits the-picture)
;; get a picture resource
(setf the-picture (#_GetPicture 128))
;; convert it into a bitmap
(setf the-bits (picture-to-bitmap the-picture))
;; plot the new image on the screen
(plot-bitmap the-bits 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap the-bits))
notes:
none.
bitmap-to-picture
formal declaration:
(bitmap-to-picture bitmap) -> a picture handle
arguments:
bits a bitmap pointer
return value:
a handle to a QuickDraw picture.
if an error occurs, the picture's picFrame will be
an empty rectangle.
description:
bitmap-to-picture returns a QuickDraw picture that will draw the
image stored in the bitmap. bitmap-to-picture is the inverse
of picture-to-bitmap
example application:
In this example, we create a bitmap and convert it into a QuickDraw
picture.
(prog (the-bits the-picture)
;; create a new bitmap
(setf the-bits (new-bitmap 100 200))
;; normally, we'd draw an image on the bitmap here
;; turn the bitmap into a picture
(setf the-picture (bitmap-to-picture the-bits))
;; store the picture to the clipboard or somewhere appropriate
...
;; recover the storage
(kill-bitmap the-bits))
notes:
QuickDraw pictures are a good way to store image data.
and-bitmaps
formal declaration:
(and-bitmaps bitmap-a bitmap-b) -> a bitmap
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ANDing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
and-bitmaps logically ANDs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and AND them together creating
a third bitmap.
(prog (a b c)
;; create a new bitmap
(setf a (new-bitmap 100 100))
(setf b (new-bitmap 100 100))
;; normally, we'd draw into the bitmaps here
;; and the two bitmaps together
(setf c (and-bitmaps a b))
;; plot the new image on the screen
(plot-bitmap c 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap a b c))
notes:
useful for calculating the intersection of two sets of bits.
or-bitmaps
formal declaration:
(or-bitmaps bitmap-a bitmap-b) -> a bitmap
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
or-bitmaps logically ORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and OR them together creating
a third bitmap.
(prog (a b c)
;; create a new bitmap
(setf a (new-bitmap 100 100))
(setf b (new-bitmap 100 100))
;; normally, we'd draw into the bitmaps here
;; and the two bitmaps together
(setf c (or-bitmaps a b))
;; plot the new image on the screen
(plot-bitmap c 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap a b c))
notes:
useful for calculating the union of two sets of bits.
xor-bitmaps
formal declaration:
(xor-bitmaps bitmap-a bitmap-b) -> a bitmap
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of XORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
xor-bitmaps logically XORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and XOR them together creating
a third bitmap.
(prog (a b c)
;; create a new bitmap
(setf a (new-bitmap 100 100))
(setf b (new-bitmap 100 100))
;; normally, we'd draw into the bitmaps here
;; and the two bitmaps together
(setf c (xor-bitmaps a b))
;; plot the new image on the screen
(plot-bitmap c 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap a b c))
notes:
useful for calculating the difference of two sets of bits.
complement-bitmap
formal declaration:
(complement-bitmap bitmap) -> a bitmap
arguments:
a a bitmap pointer
return value:
a bitmap pointer containing the logical result of complementing the
raster data from bitmap a.
if an error occurs, NULL is returned.
description:
complement-bitmap returns a new bitmap pointer containing the inverse
of the raster image contained in the bitmap pointer a.
example application:
In this example, we create a bitmap and it's complement.
(prog (a b)
;; create a new bitmap
(setf a (new-bitmap 100 100))
;; normally, we'd draw into the bitmaps here
;; and the two bitmaps together
(setf b (complement-bitmap a))
;; plot the new image on the screen
(plot-bitmap b 0 0 #$srcCopy)
;; recover the storage
(kill-bitmap a b))
notes:
useful for calculating the complement of a set of bits.
test-bitmap-pixel
formal declaration:
(test-bitmap-pixel bitmap x y) -> T or NIL
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to test
v the vertical position of the pixel to test
return value:
T if the pixel is 1, NIL if the pixel is 0.
description:
test-bitmap-pixel tests the value of the pixel at the location (h,v)
returning T if the pixel is 1, and NIL if the pixel
is zero.
example application:
In this example, we create a bitmap and test the pixel
located at (25, 32).
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; normally, we'd draw into the bitmaps here
;; and the two bitmaps together
(if (test-bitmap-pixel the-bits 25 32)
(princ "The pixel has the value one!")
(princ "The pixel has the value zero"))
;; recover the storage
(kill-bitmap the-bits))
notes:
attempting to test a point outside of the bitmap's bounds
will produce unpredictable results.
set-bitmap-pixel
formal declaration:
(set-bitmap-pixel bitmap hpos vpos)
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
set-bitmap-pixel sets the value of the pixel at the location (h,v) to 1.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 1.
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; set the pixel
(set-bitmap-pixel the-bits 25 32)
;; and the two bitmaps together
(if (test-bitmap-pixel the-bits 25 32)
(princ "The pixel has the value one!")
(princ "The pixel has the value zero"))
;; recover the storage
(kill-bitmap the-bits))
notes:
attempting to set a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
clear-bitmap-pixel
formal declaration:
(clear-bitmap-pixel bitmap hpos vpos)
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
clear-bitmap-pixel clears the value of the pixel at the location (h,v)
to 0.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 0.
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; set the pixel
(clear-bitmap-pixel the-bits 25 32)
;; and the two bitmaps together
(if (test-bitmap-pixel the-bits 25 32)
(princ "The pixel has the value one!")
(princ "The pixel has the value zero"))
;; recover the storage
(kill-bitmap the-bits))
notes:
attempting to clear a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
toggle-bitmap-pixel
formal declaration:
(toggle-bitmap-pixel bitmap x y) -> T or NIL
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
a boolean value indicating the state of the pixel
after the toggle operation. i.e. if the pixel is
set to the value 1, T is returned. If the pixel
is set to the value 0, NIL is returned.
description:
BitMapToggle inverts the value of the pixel at the location (h,v)
returning T if the pixel is set to 1 or NIL if the pixel
is set to 0.
example application:
In this example, we create a bitmap and invert the pixel
located at (25, 32).
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; and the two bitmaps together
(if (toggle-bitmap-pixel the-bits 25 32)
(princ "The pixel has the value one!")
(princ "The pixel has the value zero"))
;; recover the storage
(kill-bitmap the-bits))
notes:
attempting to toggle a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
with-focused-bitmap
formal declaration:
(with-focused-bitmap bitmap {form}*) -> bitmap
arguments:
bitmap a bitmap pointer
{form}* forms executed that draw into the bitmap
return value:
the bitmap parameter is returned
description:
with-focused-bitmap is a macro facility that sets up the drawing
environment such that any drawing commands in the statement
following the macro instantiation will draw into the bitmap
provided as the first parameter.
example application:
In this example, we create a bitmap and use the with-focused-bitmap
macro to do some drawing in it.
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; draw into the bitmap
(with-focused-bitmap (the-bits)
(#_MoveTo 10 10)
(#_LineTo 90 90))
;; recover the storage
(kill-bitmap the-bits))
notes:
none.
plot-bitmap
formal declaration:
(plot-bitmap bitmap hpos vpos mode)
arguments:
bits a bitmap pointer
h the horizontal location where the bitmap is drawn
v the horizontal location where the bitmap is drawn
mode transfer mode passed to copybits
return value:
none.
description:
plot-bitmap provides a simple interface for drawing a bitmap in
the current grafport. The bitmap is drawn with the top left corner
aligned with the point (h,v) using the indicated transfer mode.
mode is one of:
#$srcCopy #$srcOr #$srcXor #$srcBic #$notSrcCopy
#$notSrcOr #$notSrcXor #$notSrcBic #$patCopy #$patOr #$patXor
#$patBic #$notPatCopy #$notPatOr #$notPatXor #$notPatBic
example application:
In this example, we create a bitmap and use the WithBitMap
macro to do some drawing in it, and then we copy the result
to the current grafport at the location (75, 23) using the
plot-bitmap routine.
(prog (the-bits)
;; create a new bitmap
(setf the-bits (new-bitmap 100 100))
;; draw into the bitmap
(with-focused-bitmap (the-bits)
(#_MoveTo 10 10)
(#_LineTo 90 90))
;; draw it on the screen
(plot-bitmap the-bits 75 23 #$srcCopy)
;; recover the storage
(kill-bitmap the-bits))
notes:
plot-bitmap calls CopyBits.
string-to-bitmap
formal declaration:
(string-to-bitmap the-string &optional the-font-spec) -> a bitmap
arguments:
the-string a string
the-font-spec an optional font specification
return value:
a bitmap pointer
description:
string-to-bitmap converts the string pointed to by s into a bitmap
drawing the string onto an appropriately sized bitmap for the
given font specification string-to-bitmap is useful for
converting strings to bitmap so rotation can be applied with
rotate-bitmap-left or rotate-bitmap-right before it is displayed.
string-to-bitmap preserves the current grafport. if
the-font-spec is not provided, the system font will be used.
example application:
In this example, we create a bitmap pointer containing
the string "Hello World" (using bold, underlined,
24 point geneva font), rotate it 90 degrees to the
right, and draw the result in the current grafport
at the location (110,34) using the plot-bitmap routine.
(prog (the-bits rotated-bits)
;; create a new bitmap
(setf the-bits (string-to-bitmap "Hello World" '("Geneva" 24 :bold :underline)))
;; rotate the string
(setf rotated-bits (rotate-bitmap-right the-bits))
;; draw it on the screen
(plot-bitmap rotated-bits 110 34 #$srcCopy)
;; recover the storage
(kill-bitmap the-bits rotated-bits))
notes:
none.
get-bitmap-width
formal declaration:
(get-bitmap-width bitmap) -> the width
arguments:
bitmap a bitmap
return value:
the width of the bitmap
description:
get-bitmap-width is a convenience routine that returns
the width of a bitmap.
notes:
none.
get-bitmap-height
formal declaration:
(get-bitmap-height bitmap) -> the height
arguments:
bitmap a bitmap
return value:
the height of the bitmap
description:
get-bitmap-width is a convenience routine that returns
the height of a bitmap.
notes:
none.
file BitMapLisp.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved.
end of file
